<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.20"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>The small3d library: small3d</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="customdoxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="logo_s.png"/></td>
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">The small3d library
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.20 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="PageDoc"><div class="header">
  <div class="headertitle">
<div class="title"><a class="el" href="namespacesmall3d.html">small3d</a> </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p><a class="anchor" id="md_README"></a> <a href="https://ci.appveyor.com/project/dimi309/small3d"><img src="https://ci.appveyor.com/api/projects/status/qpm3qekslivm3kjb?svg=true" alt="Build status" class="inline"/></a></p>
<p><a href="https://github.com/dimi309/small3d">[Source Code]</a> <a href="https://dimi309.github.io/small3d">[API Documentation]</a></p>
<p>Minimalistic, open source library for making 3D games in C++</p>
<p>This library provides a sufficient level of game development functionalities for C++ developers to be able to build cross-platform games based on a single code-base. Supporting as many platforms as possible while minimising the amount of code and time needed for maintenance is favoured over richness of features and the use of cutting edge methods and technologies.</p>
<h1><a class="anchor" id="autotoc_md1"></a>
Sample games</h1>
<ul>
<li><a href="https://github.com/dimi309/gloom">Gloom</a> (open source)</li>
<li><a href="https://store.steampowered.com/app/2069750/Islet_Hell/">Islet Hell</a> (once commercially released, now free of charge, also available for <a href="https://play.google.com/store/apps/details?id=dimi309.islethelladroid">Android</a> and <a href="https://apps.apple.com/us/app/islet-hell/id1631875184">Apple iOS</a>)</li>
</ul>
<h1><a class="anchor" id="autotoc_md2"></a>
Features</h1>
<ul>
<li>3D models loaded from glTF (glb files), Wavefront (obj files) or from a native format</li>
<li>Other customised meshes and shapes</li>
<li>Texture mapping</li>
<li>Gouraud shading</li>
<li>Basic materials support (colour, transparency)</li>
<li>Shadow mapping</li>
<li>Image rendering</li>
<li>Font rendering</li>
<li>Sound (ogg and native files)</li>
<li>Collision detection</li>
<li>Frame-based animation (Wavefront)</li>
<li>Skeletal animation (glTF)</li>
</ul>
<h1><a class="anchor" id="autotoc_md3"></a>
Partly humorous list of things NOT supported</h1>
<ul>
<li>Animation read from glTF and linked directly to models without bones/joints</li>
<li>Non-PNG images</li>
<li>Scenes - no Scene data structure; just SceneObjects rendered in an infinite space</li>
<li>Ray tracing</li>
<li>ECS</li>
<li>AI</li>
<li>Crypto</li>
</ul>
<h1><a class="anchor" id="autotoc_md4"></a>
Supported platforms</h1>
<ul>
<li>Windows</li>
<li>MacOS</li>
<li>Linux (Tested on Debian, Ubuntu, Fedora and Arch)</li>
<li>FreeBSD</li>
<li>Android</li>
<li>iOS</li>
</ul>
<p>Running on OpenGL on PC and OpenGL ES on mobile, this library is extremely backwards compatible. It can run on iOS 9.3 and Android 4.1.</p>
<p>Note: There used to be Vulkan support too, but it has been discontinued. Here is an article on the reasons for this:</p>
<p><a href="https://www.gamedev.net/blogs/entry/2275791-abandoning-vulkan/">https://www.gamedev.net/blogs/entry/2275791-abandoning-vulkan/</a></p>
<p>And here is the last Vulkan commit before the Vulkan renderer got removed:</p>
<p><a href="https://github.com/dimi309/small3d/releases/tag/1.8015.last.vulkan">https://github.com/dimi309/small3d/releases/tag/1.8015.last.vulkan</a></p>
<p>Note that despite the official deprecation of OpenGL on Apple devices, OpenGL and OpenGL ES still work just fine there. If and when that changes, I will implement a renderer in Metal or something.</p>
<h1><a class="anchor" id="autotoc_md5"></a>
Tutorial</h1>
<p><a href="https://www.gamedev.net/tutorials/programming/engines-and-middleware/small3d-tutorial-r5655/">https://www.gamedev.net/tutorials/programming/engines-and-middleware/small3d-tutorial-r5655/</a></p>
<h1><a class="anchor" id="autotoc_md6"></a>
Building and deploying</h1>
<h2><a class="anchor" id="autotoc_md7"></a>
Prerequisites</h2>
<p>The following need to be installed, with the relevant environment variables and tools accessible via the command line:</p>
<ul>
<li>Some compiler (e.g. gcc, Visual Studio, clang) with C++14 support recommended as a minimum.</li>
<li>7zip (only on Windows)</li>
<li>CMake</li>
<li>Android Studio if building for Android</li>
<li>Xcode if building for iOS</li>
</ul>
<h2><a class="anchor" id="autotoc_md8"></a>
Deploying small3d for PC</h2>
<p>Run the build script which is suitable to your platform from the <code>scripts</code> directory (<code>build-vs.bat</code>, <code>build-mingw.bat</code> or <code>build.sh</code>).</p>
<p>Then, the unit tests are executed by running <code>unittests</code> binary from <code>build/bin</code>.</p>
<p>If any of this fails or you would simply like to restart the building procedure, the best way to clean the repository is by using git: </p><pre class="fragment">git clean -fdx
</pre><p>For building your own project, you need:</p>
<ul>
<li>The header files from the <code>build/include</code> directory</li>
<li>The libraries from the <code>build/lib</code> directory</li>
<li>The shaders from <code>build/shaders</code> directory</li>
<li>The <code>small3d/cmake</code> directory if you will be using cmake</li>
</ul>
<p>You can also deploy using <a href="https://conan.io">conan</a>. The conan package is provided in a <a href="https://github.com/dimi309/small3d-conan">separate repository</a>.</p>
<h2><a class="anchor" id="autotoc_md9"></a>
Deploying small3d for mobile</h2>
<p>Builds for mobile platforms can be performed by executing either <code>build-android</code> or <code>build-ios</code> from the <code>scripts</code> directory. You can then use the test projects in the <code>android</code>, <code>ios</code> and <code>ios-opengles</code> directories to check if everything works, or as a starting point for your own projects.</p>
<p>If the Android project produces an NDK or SDK related error when opened in Android Studio, just close it without exiting Android Studio and open it again.</p>
<p>Also on Android, while a game or the unit tests are running, the error <code>.../GL2Encoder.cpp:s_glGetBufferParameteriv:3386 GL error 0x502</code> might appear in the log. You can ignore it. It is produced when glGetBufferParameteriv is called in the Renderer to check if a model has already been copied to the GPU and the model is not found (as expected when it has been newly loaded).</p>
<p>Note that, while on the PC edition I use GLFW for windowing functionalities and I/O, on mobile I access the native infrastructure directly.</p>
<h2><a class="anchor" id="autotoc_md10"></a>
Boilerplate Project</h2>
<p>If you would like to start with an empty project that has the basic game loop and input already set up, you are looking for this:</p>
<p><a href="https://github.com/dimi309/small3d-boilerplate">https://github.com/dimi309/small3d-boilerplate</a></p>
<p>It is highly recommended to use this boilerplate if you intend to port your game to Android and / or iOS. While it is pretty straightforward to get this library working for the desktop and you might prefer the freedom and flexibility of working with a project set up from scratch, mobile platforms have many specificities and quirks to take care of, so the boilerplate can save you a lot of time in that respect.</p>
<h1><a class="anchor" id="autotoc_md11"></a>
Referenced libraries</h1>
<p>The following dependencies' <em>source code</em> repositories (not binaries) are distributed in this same repository (in the <code>deps</code> directory). They can be built by executing a single script (see "Building", above) and they can also be used directly in your application / game code.</p>
<ul>
<li>glew when building for PC</li>
<li>glfw</li>
<li>glm</li>
<li>png</li>
<li>zlib</li>
<li>ogg</li>
<li>vorbis</li>
<li>portaudio</li>
<li>freetype</li>
<li>bzip</li>
<li>cereal</li>
<li>oboe when building for Android </li>
</ul>
</div></div><!-- PageDoc -->
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by&#160;<a href="http://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.8.20
</small></address>
</body>
</html>
